/*
 * Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */
package javax.naming.spi;

import javax.naming.*;
import java.util.Hashtable;

/**
 * This interface represents a factory for obtaining the state of an
 * object for binding.
 * <p>
 * The JNDI framework allows for object implementations to
 * be loaded in dynamically via <em>object factories</em>.
 * For example, when looking up a printer bound in the name space,
 * if the print service binds printer names to <tt>Reference</tt>s, the printer
 * <tt>Reference</tt> could be used to create a printer object, so that
 * the caller of lookup can directly operate on the printer object
 * after the lookup.
 * <p>An <tt>ObjectFactory</tt> is responsible
 * for creating objects of a specific type.  In the above example,
 * you may have a <tt>PrinterObjectFactory</tt> for creating
 * <tt>Printer</tt> objects.
 * <p>
 * For the reverse process, when an object is bound into the namespace,
 * JNDI provides <em>state factories</em>.
 * Continuing with the printer example, suppose the printer object is
 * updated and rebound:
 * <blockquote><pre>
 * ctx.rebind("inky", printer);
 * </pre></blockquote>
 * The service provider for <tt>ctx</tt> uses a state factory
 * to obtain the state of <tt>printer</tt> for binding into its namespace.
 * A state factory for the <tt>Printer</tt> type object might return
 * a more compact object for storage in the naming system.
 * <p>
 * A state factory must implement the <tt>StateFactory</tt> interface.
 * In addition, the factory class must be public and must have a
 * public constructor that accepts no parameters.
 * <p>
 * The <tt>getStateToBind()</tt> method of a state factory may
 * be invoked multiple times, possibly using different parameters.
 * The implementation is thread-safe.
 * <p>
 * <tt>StateFactory</tt> is intended for use with service providers
 * that implement only the <tt>Context</tt> interface.
 * <tt>DirStateFactory</tt> is intended for use with service providers
 * that implement the <tt>DirContext</tt> interface.
 *
 * @author Rosanna Lee
 * @author Scott Seligman
 * @see NamingManager#getStateToBind
 * @see DirectoryManager#getStateToBind
 * @see ObjectFactory
 * @see DirStateFactory
 * @since 1.3
 */
public interface StateFactory {

  /**
   * Retrieves the state of an object for binding.
   * <p>
   * <tt>NamingManager.getStateToBind()</tt>
   * successively loads in state factories and invokes this method
   * on them until one produces a non-null answer.
   * <tt>DirectoryManager.getStateToBind()</tt>
   * successively loads in state factories.  If a factory implements
   * <tt>DirStateFactory</tt>, then <tt>DirectoryManager</tt>
   * invokes <tt>DirStateFactory.getStateToBind()</tt>; otherwise
   * it invokes <tt>StateFactory.getStateToBind()</tt>.
   * <p> When an exception
   * is thrown by a factory, the exception is passed on to the caller
   * of <tt>NamingManager.getStateToBind()</tt> and
   * <tt>DirectoryManager.getStateToBind()</tt>.
   * The search for other factories
   * that may produce a non-null answer is halted.
   * A factory should only throw an exception if it is sure that
   * it is the only intended factory and that no other factories
   * should be tried.
   * If this factory cannot create an object using the arguments supplied,
   * it should return null.
   * <p>
   * The <code>name</code> and <code>nameCtx</code> parameters may
   * optionally be used to specify the name of the object being created.
   * See the description of "Name and Context Parameters" in
   * {@link ObjectFactory#getObjectInstance ObjectFactory.getObjectInstance()}
   * for details.
   * If a factory uses <code>nameCtx</code> it should synchronize its use
   * against concurrent access, since context implementations are not
   * guaranteed to be thread-safe.
   * <p>
   * The <tt>name</tt> and <tt>environment</tt> parameters
   * are owned by the caller.
   * The implementation will not modify these objects or keep references
   * to them, although it may keep references to clones or copies.
   *
   * @param obj A non-null object whose state is to be retrieved.
   * @param name The name of this object relative to <code>nameCtx</code>, or null if no name is
   * specified.
   * @param nameCtx The context relative to which the <code>name</code> parameter is specified, or
   * null if <code>name</code> is relative to the default initial context.
   * @param environment The possibly null environment to be used in the creation of the object's
   * state.
   * @return The object's state for binding; null if the factory is not returning any changes.
   * @throws NamingException if this factory encountered an exception while attempting to get the
   * object's state, and no other factories are to be tried.
   * @see NamingManager#getStateToBind
   * @see DirectoryManager#getStateToBind
   */
  public Object getStateToBind(Object obj, Name name, Context nameCtx,
      Hashtable<?, ?> environment)
      throws NamingException;
}
